home *** CD-ROM | disk | FTP | other *** search
/ Amiga Plus 1995 #5 & #6 / Amiga Plus CD - 1995 - No. 5 and 6.iso / tex / man / makeindex.hlp < prev    next >
Text File  |  1991-10-01  |  34KB  |  1,057 lines
  1.  
  2.  
  3.  
  4. MAKEINDEX(1L)     MISC. REFERENCE MANUAL PAGES      MAKEINDEX(1L)
  5.  
  6.  
  7.  
  8. NAME
  9.      makeindex - a general purpose,  formatter-independent  index
  10.      processor
  11.  
  12. SYNOPSIS
  13.      makeindex [-c] [-g] [-i] [-l] [-o ind] [-p  num]  [-q]  [-r]
  14.      [-s sfile] [-t log] [idx0 idx1 idx2...]
  15.  
  16. DESCRIPTION
  17.      The program makeindex  is  a  general  purpose  hierarchical
  18.      index  generator;  it accepts one or more input files (often
  19.      produced by a  text  formatter  such  as  TeX  (tex(1L))  or
  20.      troff(1),  sorts  the  entries,  and produces an output file
  21.      which can be formatted.  The index can have up to three lev-
  22.      els  (0,  1,  and  2)  of subitem nesting.  The way in which
  23.      words are flagged for indexing within the main  document  is
  24.      specific  to the formatter used; makeindex does not automate
  25.      the process of selecting these words.  As the  output  index
  26.      is  hierarchical,  makeindex can be considered complimentary
  27.      to the awk(1)-based make.index(1L)  system  of  Bentley  and
  28.      Kernighan,  which  is  specific  to troff(1), generates non-
  29.      hierarchical indices, and employs a much simpler syntax  for
  30.      indicating  index  entries.   For  illustration  of use with
  31.      troff and TeX, see the section EXAMPLES below.
  32.  
  33.      The formats of the input and output files are specified in a
  34.      style  file; by default, input is assumed to be a .idx file,
  35.      as generated by LaTeX.
  36.  
  37.      Unless specified explicitly, the  base  name  of  the  first
  38.      input  file  (idx0)  is used to determine the names of other
  39.      files.  For each input file name specified, a file  of  that
  40.      name is sought.  If this file is not found and the file name
  41.      has no extension, the extension .idx  is  appended.   If  no
  42.      file with this name is found, makeindex aborts.
  43.  
  44.      For important notes on how to select index keywords, see the
  45.      document  by Lamport cited below.  As an issue separate from
  46.      selecting index keywords, a systematic mechanism for placing
  47.      index  terms in a document is suggested in Index Preparation
  48.      and Processing, a paper cited below.
  49.  
  50. OPTIONS
  51.      -c        Compress intermediate blanks (ignoring leading and
  52.                trailing  blanks and tabs).  By default, blanks in
  53.                the index key are retained.
  54.  
  55.      -g        Employ German  word  ordering  in  the  index,  in
  56.                accord  with  rules  set  forth  in  DIN 5007.  By
  57.                default, makeindex  employs  a  word  ordering  in
  58.                which  precedence  is: symbols, numbers, uppercase
  59.                letters,  lowercase  letters.   The  sequence   in
  60.  
  61.  
  62.  
  63. Sun Release 4.1   Last change: 01 October 1991                  1
  64.  
  65.  
  66.  
  67.  
  68.  
  69.  
  70. MAKEINDEX(1L)     MISC. REFERENCE MANUAL PAGES      MAKEINDEX(1L)
  71.  
  72.  
  73.  
  74.                German   word   ordering  is:  symbols,  lowercase
  75.                letters, uppercase  letters,  numbers.   Addition-
  76.                ally,  this  option enables makeindex to recognize
  77.                the German TeX-commands {"a, "o,  "u  and  "s}  as
  78.                {ae,  oe,  ue  and  ss}  during the sorting of the
  79.                entries.  The quote character must be redefined in
  80.                a style file (for example, redefine quote as '+').
  81.                If the quote character is not redefined, makeindex
  82.                will produce an error message and abort.
  83.  
  84.      -i        Take input from stdin.  When this option is speci-
  85.                fied and -o is not, output is written to stdout.
  86.  
  87.      -l        Letter ordering; by default, word ordering is used
  88.                (see the ORDERING section).
  89.  
  90.      -o ind    Employ ind as the output index file.  By  default,
  91.                the  file  name is created by appending the exten-
  92.                sion .ind to the base name of the first input file
  93.                (idx0).
  94.  
  95.      -p num    Set the starting page number of the  output  index
  96.                file  to  be num (useful when the index file is to
  97.                be formatted separately).  The argument num may be
  98.                numerical or one of the following:
  99.  
  100.                any       The starting page  is  the  last  source
  101.                          page number plus 1.
  102.  
  103.                odd       The starting page is the first odd  page
  104.                          following the last source page number.
  105.  
  106.                even      The starting page is the first even page
  107.                          following the last source page number.
  108.  
  109.                The last source  page  is  obtained  by  searching
  110.                backward in the log file for the first instance of
  111.                a number included within  paired  square  brackets
  112.                ([...]).   If  a page number is missing or the log
  113.                file is not found, no attempt will be made to  set
  114.                the  starting  page  number.   The source log file
  115.                name is determined by appending the extension .log
  116.                to the base name of the first input file (idx0).
  117.  
  118.      -q        Quiet  mode;  send  no  messages  to  stderr.   By
  119.                default,  progress  and error messages are sent to
  120.                stderr as well as to the transcript file.
  121.  
  122.      -r        Disable implicit page range formation; page ranges
  123.                must be created by using explicit range operators;
  124.                see SPECIAL EFFECTS below.  By default,  three  or
  125.                more    successive    pages    are   automatically
  126.  
  127.  
  128.  
  129. Sun Release 4.1   Last change: 01 October 1991                  2
  130.  
  131.  
  132.  
  133.  
  134.  
  135.  
  136. MAKEINDEX(1L)     MISC. REFERENCE MANUAL PAGES      MAKEINDEX(1L)
  137.  
  138.  
  139.  
  140.                abbreviated as a range (e.g. 1-5).
  141.  
  142.      -s sty    Employ sty as the style file  (no  default).   The
  143.                environment  variable  INDEXSTYLE defines the path
  144.                where the style file should be found.
  145.  
  146.      -t log    Employ log as the transcript  file.   By  default,
  147.                the  file  name is created by appending the exten-
  148.                sion .ilg to the base name of the first input file
  149.                (idx0).
  150.  
  151. STYLE FILE
  152.      The style file informs makeindex about  the  format  of  the
  153.      .idx input files and the intended format of the final output
  154.      file; examples appear below.  This file can reside  anywhere
  155.      in  the path defined by the environment variable INDEXSTYLE.
  156.      The style file contains a  list  of  <specifier,  attribute>
  157.      pairs.  There are two types of specifiers: input and output.
  158.      Pairs do not have to appear in any particular order.  A line
  159.      begun by `%' is a comment.  In the following list of specif-
  160.      iers and arguments, <string> is an arbitrary  string  delim-
  161.      ited  by  double  quotes  ("..."), <char> is a single letter
  162.      embraced by single quotes ('...'), and <number> is a  nonne-
  163.      gative  integer.   The maximum length of a <string> is 2048.
  164.      A  literal  backslash  or  quote  must  be  escaped  (by   a
  165.      backslash).   Anything  not specified in the style file will
  166.      be assigned a default value, which is shown at the  head  of
  167.      the rightmost column.
  168.  
  169.   INPUT STYLE SPECIFIERS
  170.      actual <char>            '@'
  171.                               Symbol  indicating  that  the  next
  172.                               entry  is  to  appear in the output
  173.                               file.
  174.  
  175.      arg_close <char>         '}'
  176.                               Closing  delimiter  for  the  index
  177.                               entry argument.
  178.  
  179.      arg_open <char>          '{'
  180.                               Opening  delimiter  for  the  index
  181.                               entry argument.
  182.  
  183.      encap <char>             '|'
  184.                               Symbol indicating that the rest  of
  185.                               the  argument list is to be used as
  186.                               the encapsulating command  for  the
  187.                               page number.
  188.  
  189.      escape <char>            '\\'
  190.                               Symbol which escapes the  following
  191.                               letter, unless its preceding letter
  192.  
  193.  
  194.  
  195. Sun Release 4.1   Last change: 01 October 1991                  3
  196.  
  197.  
  198.  
  199.  
  200.  
  201.  
  202. MAKEINDEX(1L)     MISC. REFERENCE MANUAL PAGES      MAKEINDEX(1L)
  203.  
  204.  
  205.  
  206.                               is escape.  Note: quote is used  to
  207.                               escape the letter which immediately
  208.                               follows it, but if it  is  preceded
  209.                               by escape, it is treated as a ordi-
  210.                               nary character.  These two  symbols
  211.                               must be distinct.
  212.  
  213.      keyword <string>         "\\indexentry"
  214.                               Command which tells makeindex  that
  215.                               its argument is an index entry.
  216.  
  217.      level <char>             '!'
  218.                               Delimiter denoting a new  level  of
  219.                               subitem.
  220.  
  221.      quote <char>             '"'
  222.                               Note: quote is used to  escape  the
  223.                               letter  which  immediately  follows
  224.                               it,  but  if  it  is  preceded   by
  225.                               escape, it is treated as a ordinary
  226.                               character.  These two symbols  must
  227.                               be distinct.
  228.  
  229.      range_close <char>       ')'
  230.                               Closing  delimiter  indicating  the
  231.                               end of an explicit page range.
  232.  
  233.      range_open <char>        '('
  234.                               Opening  delimiter  indicating  the
  235.                               beginning   of   an  explicit  page
  236.                               range.
  237.  
  238.   OUTPUT STYLE SPECIFIERS
  239.      preamble <string>        "\\begin{theindex}\n"
  240.                               Preamble of output file.
  241.  
  242.      postamble <string>       "\n\n\\end{theindex}\n"
  243.                               Postamble of output file.
  244.  
  245.      setpage_prefix <string>  "\n  \\setcounter{page}{"
  246.                               Prefix of command  which  sets  the
  247.                               starting page number.
  248.  
  249.      setpage_suffix <string>  "}\n"
  250.                               Suffix of command  which  sets  the
  251.                               starting page number.
  252.  
  253.      group_skip <string>      "\n\n  \\indexspace\n"
  254.                               Vertical  space  to   be   inserted
  255.                               before a new group begins.
  256.  
  257.      headings_flag <string>   0
  258.  
  259.  
  260.  
  261. Sun Release 4.1   Last change: 01 October 1991                  4
  262.  
  263.  
  264.  
  265.  
  266.  
  267.  
  268. MAKEINDEX(1L)     MISC. REFERENCE MANUAL PAGES      MAKEINDEX(1L)
  269.  
  270.  
  271.  
  272.                               Flag indicating  treatment  of  new
  273.                               group  headers,  which are inserted
  274.                               when before a new  group  (symbols,
  275.                               numbers, and the 26 letters): posi-
  276.                               tive  values  cause  an   uppercase
  277.                               letter  to be inserted between pre-
  278.                               fix and suffix, and negative values
  279.                               cause  a  lowercase  letter  to  be
  280.                               inserted (default is 0, which  pro-
  281.                               duces no header).
  282.  
  283.      heading_prefix <string>  ""
  284.                               Header prefix to be inserted before
  285.                               a new letter begins.
  286.  
  287.      symhead_positive <string>
  288.                               "Symbols"
  289.                               Heading for symbols to be  inserted
  290.                               if headings_flag is positive.
  291.  
  292.      symhead_negative <string>
  293.                               "symbols"
  294.                               Heading for symbols to be  inserted
  295.                               if headings_flag is negative.
  296.  
  297.      numhead_positive <string>
  298.                               "Numbers"
  299.                               Heading for numbers to be  inserted
  300.                               if headings_flag is positive.
  301.  
  302.      numhead_negative <string>
  303.                               "numbers"
  304.                               Heading for numbers to be  inserted
  305.                               if headings_flag is negative.
  306.  
  307.      item_0 <string>          "\n  \\item "
  308.                               Command to be inserted between  two
  309.                               primary (level 0) items.
  310.  
  311.      item_1 <string>          "\n     \\subitem "
  312.                               Command to be inserted between  two
  313.                               secondary (level 1) items.
  314.  
  315.      item_2 <string>          "\n       \\subsubitem "
  316.                               Command to be inserted between  two
  317.                               level 2 items.
  318.  
  319.      item_01  <string>        "\n    \\subitem "
  320.                               Command to be  inserted  between  a
  321.                               level 0 item and a level 1 item.
  322.  
  323.      item_x1 <string>         "\n    \\subitem "
  324.  
  325.  
  326.  
  327. Sun Release 4.1   Last change: 01 October 1991                  5
  328.  
  329.  
  330.  
  331.  
  332.  
  333.  
  334. MAKEINDEX(1L)     MISC. REFERENCE MANUAL PAGES      MAKEINDEX(1L)
  335.  
  336.  
  337.  
  338.                               Command to be  inserted  between  a
  339.                               level  0  item  and a level 1 item,
  340.                               where the level  0  item  does  not
  341.                               have associated page numbers.
  342.  
  343.      item_12 <string>         "\n    \\subsubitem "
  344.                               Command to be  inserted  between  a
  345.                               level 1 item and a level 2 item.
  346.  
  347.      item_x2 <string>         "\n    \\subsubitem "
  348.                               Command to be  inserted  between  a
  349.                               level  1  item  and a level 2 item,
  350.                               where the level  1  item  does  not
  351.                               have associated page numbers.
  352.  
  353.      delim_0 <string>         ", "
  354.                               Delimiter to be inserted between  a
  355.                               level  0  key  and  its  first page
  356.                               number (default: comma followed  by
  357.                               a blank).
  358.  
  359.      delim_1 <string>         ", "
  360.                               Delimiter to be inserted between  a
  361.                               level  1  key  and  its  first page
  362.                               number (default: comma followed  by
  363.                               a blank).
  364.  
  365.      delim_2 <string>         ", "
  366.                               Delimiter to be inserted between  a
  367.                               level  2  key  and  its  first page
  368.                               number (default: comma followed  by
  369.                               a blank).
  370.  
  371.      delim_n <string>         ", "
  372.                               Delimiter to  be  inserted  between
  373.                               two  page  numbers for the same key
  374.                               in any level (default:  comma  fol-
  375.                               lowed by a blank).
  376.  
  377.      delim_r <string>         "--"
  378.                               Delimiter to  be  inserted  between
  379.                               the   starting   and   ending  page
  380.                               numbers of a range.
  381.  
  382.      delim_t <string>         ""
  383.                               Delimiter to be inserted at the end
  384.                               of a page list.  This delimiter has
  385.                               no effect on entries which have  no
  386.                               associated page list.
  387.  
  388.      encap_prefix <string>    "\\"
  389.                               First  part  of  prefix   for   the
  390.  
  391.  
  392.  
  393. Sun Release 4.1   Last change: 01 October 1991                  6
  394.  
  395.  
  396.  
  397.  
  398.  
  399.  
  400. MAKEINDEX(1L)     MISC. REFERENCE MANUAL PAGES      MAKEINDEX(1L)
  401.  
  402.  
  403.  
  404.                               command which encapsulates the page
  405.                               number.
  406.  
  407.      encap_infix <string>     "{"
  408.                               Second part of prefix for the  com-
  409.                               mand  which  encapsulates  the page
  410.                               number.
  411.  
  412.      encap_suffix <string>    "}".
  413.                               Suffix for the command which encap-
  414.                               sulates the page number.
  415.  
  416.      line_max <number>        72
  417.                               Maximum length of  a  line  in  the
  418.                               output, beyond which a line wraps.
  419.  
  420.      indent_space <string>    "\t\t"
  421.                               Space to be inserted in front of  a
  422.                               wrapped line (default: two tabs).
  423.  
  424.      indent_length <number>   16
  425.                               Length  of  indent_space  (default:
  426.                               16, equivalent to 2 tabs).
  427.  
  428. EXAMPLES
  429.   TeX EXAMPLE
  430.      The following example shows a style  file  called  book.ist,
  431.      which  defines  an  index  for a book which can be formatted
  432.      independently of the main source:
  433.  
  434.           preamble
  435.           "\\documentstyle[12pt]{book}
  436.           \\begin{document}
  437.           \\begin{theindex}
  438.           {\\small\n"
  439.           postamble
  440.           "\n\n}
  441.           \\end{theindex}
  442.           \\end{document}\n"
  443.  
  444.      Assuming that a particular book style requires the index (as
  445.      well  as any chapters) to start from an odd page number, and
  446.      that the input file is named foo.idx, the following  command
  447.      line produces output in file footmp.ind:
  448.  
  449.           makeindex  -s book.ist  -o footmp.ind  -p odd  foo
  450.  
  451.      Here a  non-default  output  file  name  is  used  to  avoid
  452.      clobbering  the  output  for  the  book  itself  (presumably
  453.      foo.dvi, which would have been  the  default  name  for  the
  454.      index output file!).
  455.  
  456.  
  457.  
  458.  
  459. Sun Release 4.1   Last change: 01 October 1991                  7
  460.  
  461.  
  462.  
  463.  
  464.  
  465.  
  466. MAKEINDEX(1L)     MISC. REFERENCE MANUAL PAGES      MAKEINDEX(1L)
  467.  
  468.  
  469.  
  470.   TROFF EXAMPLE
  471.      A sample control file for creating an index, which  we  will
  472.      assume resides in the file sample.ist:
  473.  
  474.           keyword "IX:"
  475.           preamble
  476.           ".\\\" start of index output
  477.           \".\\\" enter two column mode
  478.           .2C
  479.           .SH
  480.           .ce
  481.           INDEX
  482.           .XS
  483.           INDEX
  484.           .XE
  485.           .R
  486.           .ps 9p
  487.           .vs 11p
  488.           .sp
  489.           .de I1
  490.           .ti 0.25i
  491.           ..
  492.           .de I2
  493.           .ti 0.5i
  494.           .."
  495.           postamble "\n.\\\" end of index output"
  496.           setpage_prefix "\n.nr % "
  497.           setpage_suffix ""
  498.           group_skip "\n.sp 1.0"
  499.           headings_flag 1
  500.           heading_prefix "\n.IS\n"
  501.           heading_suffix "\n.IE"
  502.           item_0 "\n.br\n"
  503.           item_1 "\n.I1\n"
  504.           item_2 "\n.I2\n"
  505.           item_01 "\n.I1\n"
  506.           item_x1 "\n.I1\n"
  507.           item_12 "\n.I2\n"
  508.           item_x2 "\n.I2\n"
  509.           delim_0 ", "
  510.           delim_1 ", "
  511.           delim_2 ", "
  512.           delim_r "-"
  513.           delim_t "."
  514.           encap_prefix "\\fB"
  515.           encap_infix ""
  516.           encap_suffix "\\fP"
  517.           indent_space ""
  518.           indent_length 0
  519.  
  520.      The local macro package may require modification, as in this
  521.      example of an extension to the -ms macros (note that at some
  522.  
  523.  
  524.  
  525. Sun Release 4.1   Last change: 01 October 1991                  8
  526.  
  527.  
  528.  
  529.  
  530.  
  531.  
  532. MAKEINDEX(1L)     MISC. REFERENCE MANUAL PAGES      MAKEINDEX(1L)
  533.  
  534.  
  535.  
  536.      sites, this macro should replace a pre-existing macro of the
  537.      same name):
  538.  
  539.           .
  540.           .de IX
  541.           .ie '\\n(.z'' .tm IX: \\$1 \\$2 \\$3 \\$4 \\$5 \\$6 \\$7 \\$8 \\$9 {\\n(PN}
  542.           .el \\!.IX \\$1 \\$2 \\$3 \\$4 \\$5 \\$6 \\$7 \\$8 \\$9 {\\n(PN}
  543.           ..
  544.  
  545.      (note that the string {\\n(PN} is separated from the rest of
  546.      the  line  by  a  tab.  If your local macro package does not
  547.      contain this extension, just  include  those  lines  at  the
  548.      beginning  of  your  file.   Here is a simple troff(1) input
  549.      file, which we will assume is named sample.txt:
  550.  
  551.           This is a sample file to test the \fImakeindex\fP(1L)
  552.           program, and see
  553.           .IX {indexing!programs!C language}
  554.           .IX {makeindex@\fImakeindex\fP(1L)}
  555.           .bp
  556.           .rs
  557.           .IX {Knuth}
  558.           .IX {typesetting!computer-aided}
  559.           how well it functions in the \fItroff\fP(1) environment.
  560.  
  561.      Note that index entries are  indicated  by  the  .IX  macro,
  562.      which  causes  the  following  text  to be written to stdout
  563.      along with the current page number.
  564.  
  565.   CREATING THE INDEX FILE IN THE BOURNE SHELL
  566.      To create an input file for makeindex, in the  Bourne  shell
  567.      environment, do the equivalent at your site of the command:
  568.  
  569.      psroff -ms -Tpsc -t sample.txt > /dev/null 2> sample.tmp
  570.  
  571.      Some sites will  require  ditroff  instead  of  psroff.   To
  572.      filter out any genuine error messages, invoke grep(1):
  573.  
  574.           grep '^IX: ' sample.tmp > sample.idx
  575.  
  576.   CREATING THE INDEX FILE USING UCSF ENHANCED TROFF/TRANSCRIPT
  577.  
  578.      With  UCSF  Enhanced  troff/TRANSCRIPT,  the  -I  option  of
  579.      psroff(1L)  can  produce  both formatter output and an index
  580.      file:
  581.  
  582.           psroff -ms -I sample.inp -Tpsc sample.txt
  583.  
  584.      If it is wished to suppress the formatter output:
  585.  
  586.           psroff -ms -I sample.inp -Tpsc -t sample.txt > /dev/null
  587.  
  588.  
  589.  
  590.  
  591. Sun Release 4.1   Last change: 01 October 1991                  9
  592.  
  593.  
  594.  
  595.  
  596.  
  597.  
  598. MAKEINDEX(1L)     MISC. REFERENCE MANUAL PAGES      MAKEINDEX(1L)
  599.  
  600.  
  601.  
  602.   COMPLETING THE INDEX
  603.      Any of the above procedures leaves the input  for  makeindex
  604.      in sample.inp.  The next step is to invoke makeindex:
  605.  
  606.           makeindex -s sample.ist sample.idx
  607.  
  608.      This leaves troff(1)-ready output in the file sample.ind.
  609.  
  610. ORDERING
  611.      By default, makeindex  assumes  word  ordering;  if  the  -l
  612.      option  is in effect, letter ordering is used.  In word ord-
  613.      ering, a blank precedes any letter in the alphabet,  whereas
  614.      in  letter  ordering,  it  does  not  count at all.  This is
  615.      illustrated by the following example:
  616.  
  617.           word order                      letter order
  618.           sea lion                        seal
  619.           seal                            sea lion
  620.  
  621.      Numbers are always sorted in numeric order.  For instance,
  622.  
  623.           9 (nine),  123
  624.           10 (ten), see Derek, Bo
  625.  
  626.      Letters are first sorted without regard to case; when  words
  627.      are  identical, the uppercase version precedes its lowercase
  628.      counterpart.
  629.  
  630.      A special symbol is defined here to  be  any  character  not
  631.      appearing  in the union of digits and the English alphabetic
  632.      characters.  Patterns starting with special symbols  precede
  633.      numbers, which precede patterns starting with letters.  As a
  634.      special case, a string starting with a digit but mixed  with
  635.      non-digits  is  considered  to  be a pattern starting with a
  636.      special character.
  637.  
  638. SPECIAL EFFECTS
  639.      Entries such as
  640.  
  641.           \indexentry{alpha}{1}
  642.           \indexentry{alpha!beta}{3}
  643.           \indexentry{alpha!beta!gamma}{10}
  644.  
  645.      in the input file will be converted to
  646.  
  647.           \item alpha, 1
  648.              \subitem beta, 3
  649.                 \subsubitem gamma, 10
  650.  
  651.      in the output index file.   Notice  that  the  level  symbol
  652.      (`!') is used above to delimit hierarchical levels.
  653.  
  654.  
  655.  
  656.  
  657. Sun Release 4.1   Last change: 01 October 1991                 10
  658.  
  659.  
  660.  
  661.  
  662.  
  663.  
  664. MAKEINDEX(1L)     MISC. REFERENCE MANUAL PAGES      MAKEINDEX(1L)
  665.  
  666.  
  667.  
  668.      It is possible to make an item appear in a  designated  form
  669.      by using the actual (`@') operator.  For instance,
  670.  
  671.           \indexentry{alpha@{\it alpha\/}}{1}
  672.  
  673.      will become
  674.  
  675.           \item {\it alpha\/},  1
  676.  
  677.      after processing.  The pattern preceding `@' is used as sort
  678.      key,  whereas  the one following it is written to the output
  679.      file.  Note that two appearances of the same key,  one  with
  680.      and  one  without  the actual operator, are regarded as dis-
  681.      tinct entries.
  682.  
  683.      The item, subitem, and subsubitem fields may have individual
  684.      sort keys:
  685.  
  686.           \indexentry{aa@{\it aa\/}!bb@{\it bb\/}!cc@{\it cc\/}}{1}
  687.  
  688.      This will be converted to
  689.  
  690.           \item {\it aa}, 1
  691.              \subitem {\it bb}, 3
  692.                 \subsubitem {\it cc}, 10
  693.  
  694.      It is possible to encapsulate a page number  with  a  desig-
  695.      nated command using the encap (`|') operator:
  696.  
  697.           \indexentry{alpha|bold}{1}
  698.  
  699.      will be converted to
  700.  
  701.           \item alpha, \bold{1}
  702.  
  703.      where, with a suitable definition  for  TeX,  \bold{n}  will
  704.      expand to {\bf n}.  In this example, the three output attri-
  705.      butes  associated  with  page  encapsulation   encap_prefix,
  706.      encap_infix, and encap_suffix, correspond to backslash, left
  707.      brace, and right brace, respectively.  This mechanism allows
  708.      page numbers to be set in different fonts.  For example, the
  709.      page where the definition of a keyword appears can be in one
  710.      font,  the  location  of a primary example can be in another
  711.      font, and other appearances in yet a third font.
  712.  
  713.      The encap operator can also be used to create  cross  refer-
  714.      ences in the index:
  715.  
  716.           \indexentry{alpha|see{beta}}{1}
  717.  
  718.      will become
  719.  
  720.  
  721.  
  722.  
  723. Sun Release 4.1   Last change: 01 October 1991                 11
  724.  
  725.  
  726.  
  727.  
  728.  
  729.  
  730. MAKEINDEX(1L)     MISC. REFERENCE MANUAL PAGES      MAKEINDEX(1L)
  731.  
  732.  
  733.  
  734.           \item alpha, \see{beta}{1}
  735.  
  736.      in the output file, where
  737.  
  738.           \see{beta}{1}
  739.  
  740.      will expand to
  741.  
  742.           {\it see\/} beta
  743.  
  744.      Note that in a cross reference like  this  the  page  number
  745.      disappears.
  746.  
  747.      A pair of encap  concatenated  with  range_open  (`|(')  and
  748.      range_close (`|)') creates an explicit page range:
  749.  
  750.           \indexentry{alpha|(}{1}
  751.           \indexentry{alpha|)}{5}
  752.  
  753.      will become
  754.  
  755.           \item alpha, 1-5
  756.  
  757.      Intermediate pages indexed by the same key  will  be  merged
  758.      into  the  range implicitly.  This is especially useful when
  759.      an entire section  about  a  particular  subject  is  to  be
  760.      indexed,  in  which  case only the range opening and closing
  761.      operators need to be inserted at the beginning  and  end  of
  762.      the section.  Explicit page range formation can also include
  763.      an extra command to set the page range in a designated font:
  764.  
  765.           \indexentry{alpha|(bold}{1}
  766.           \indexentry{alpha|)}{5}
  767.  
  768.      will become
  769.  
  770.           \item alpha, \bold{1--5}
  771.  
  772.      Several potential problems  are  worth  mentioning.   First,
  773.      entries like
  774.  
  775.           \indexentry{alpha|(}{1}
  776.           \indexentry{alpha|bold}{3}
  777.           \indexentry{alpha|)}{5}
  778.  
  779.      will be interpreted as
  780.  
  781.           \item alpha, \bold{3}, 1--5
  782.  
  783.      but  with  a  warning  message  in  the   transcript   about
  784.      encountering an inconsistent page encapsulator.  An explicit
  785.      range beginning in a Roman page number and ending in  Arabic
  786.  
  787.  
  788.  
  789. Sun Release 4.1   Last change: 01 October 1991                 12
  790.  
  791.  
  792.  
  793.  
  794.  
  795.  
  796. MAKEINDEX(1L)     MISC. REFERENCE MANUAL PAGES      MAKEINDEX(1L)
  797.  
  798.  
  799.  
  800.      is  also  considered an error.  In this instance, (if possi-
  801.      ble) the range is broken into two subranges,  one  in  Roman
  802.      and the other in Arabic.  For instance,
  803.  
  804.           \indexentry{alpha|(}{i}
  805.           \indexentry{alpha}{iv}
  806.           \indexentry{alpha}{3}
  807.           \indexentry{alpha|)}{7}
  808.  
  809.      will be turned into
  810.  
  811.           \item alpha, i--iv, 3--7
  812.  
  813.      with a warning message in the  transcript  file  complaining
  814.      about an illegal range formation.
  815.  
  816.      Finally, every special symbol mentioned in this section  may
  817.      be escaped by the quote operator (`"').  Thus
  818.  
  819.           \indexentry{alpha"@beta}{1}
  820.  
  821.      will actually become
  822.  
  823.           \item alpha@beta,  1
  824.  
  825.      as a result of executing makeindex.  The  quoting  power  of
  826.      quote  is eliminated if it is immediately preceded by escape
  827.      (`\').  For example,
  828.  
  829.           \indexentry{f\"ur}{1}
  830.  
  831.      becomes
  832.  
  833.           \item f\"ur, 1
  834.  
  835.      which represents an umlaut-accented `u' to the TeX family of
  836.      processors.
  837.  
  838.      From version 2.11 of makeindex, the quote operator may quote
  839.      any  character  in  the  range  1  ... 255.   Character 0 is
  840.      excluded because it is  used  internally  in  the  makeindex
  841.      source  code as a string terminator.  With this change, sort
  842.      keys can be created for all eight-bit characters  except  0.
  843.      The sorting order is
  844.  
  845.           punctuation characters (in ASCII order),
  846.           digits,
  847.           control characters (1 ... 31),
  848.           space (32),
  849.           letters (ignoring case),
  850.           characters 127 ... 255.
  851.  
  852.  
  853.  
  854.  
  855. Sun Release 4.1   Last change: 01 October 1991                 13
  856.  
  857.  
  858.  
  859.  
  860.  
  861.  
  862. MAKEINDEX(1L)     MISC. REFERENCE MANUAL PAGES      MAKEINDEX(1L)
  863.  
  864.  
  865.  
  866.      Here is an example showing the  indexing  of  all  printable
  867.      ASCII characters other than letters and digits, assuming the
  868.      default TeX format.  For convenience, the page number refer-
  869.      ences are the corresponding ASCII ordinal values.
  870.  
  871.           \indexentry{" @"  (space)}{32}
  872.           \indexentry{"!@"! (exclamation point)}{33}
  873.           \indexentry{""@"" (quotation mark))}{34}
  874.           \indexentry{"#@"\# (sharp sign)}{35}
  875.           \indexentry{"$@"\$ (dollar sign)}{36}
  876.           \indexentry{"%@"\% (percent sign)}{37}
  877.           \indexentry{"&@"\& (ampersand)}{38}
  878.           \indexentry{"<@"$<$ (left angle bracket)}{60}
  879.           \indexentry{"=@"= (equals)}{61}
  880.           \indexentry{">@"$>$ (right angle bracket)}{62}
  881.           \indexentry{"?@"? (query)}{63}
  882.           \indexentry{"@@"@ (at sign)}{64}
  883.           \indexentry{"[@"[ (left square bracket)}{91}
  884.           \indexentry{"\@"\verb=\= (backslash)}{92}
  885.           \indexentry{"]@"] (right square bracket)}{93}
  886.           \indexentry{"^@"\verb=^= (caret)}{94}
  887.           \indexentry{"_@"\verb=_= (underscore)}{95}
  888.           \indexentry{"`@"\verb=~= (grave accent)}{96}
  889.           \indexentry{"{@"\"{ (left brace)}{123}
  890.           \indexentry{"|@"\verb="|= (vertical bar)}{124}
  891.           \indexentry{"}@"\"} (right brace)}{125}
  892.           \indexentry{"~@"\verb=~= (tilde)}{126}
  893.  
  894.      Characters in the actual fields following the `@'  character
  895.      which  have  special significance to TeX must be represented
  896.      as control sequences, or as math mode characters.  Note par-
  897.      ticularly  how  the  entries for the at sign, left and right
  898.      braces, and the vertical bar, are  coded.   The  index  file
  899.      output by makeindex for this example looks like this:
  900.  
  901.           \begin{theindex}
  902.  
  903.             \item ! (exclamation point), 33
  904.             \item " (quotation mark)), 34
  905.             \item \# (sharp sign), 35
  906.             \item \$ (dollar sign), 36
  907.             \item \% (percent sign), 37
  908.             \item \& (ampersand), 38
  909.             \item $<$ (left angle bracket), 60
  910.             \item = (equals), 61
  911.             \item $>$ (right angle bracket), 62
  912.             \item ? (query), 63
  913.             \item @ (at sign), 64
  914.             \item [ (left square bracket), 91
  915.             \item \verb=\= (backslash), 92
  916.             \item ] (right square bracket), 93
  917.             \item \verb=^= (caret), 94
  918.  
  919.  
  920.  
  921. Sun Release 4.1   Last change: 01 October 1991                 14
  922.  
  923.  
  924.  
  925.  
  926.  
  927.  
  928. MAKEINDEX(1L)     MISC. REFERENCE MANUAL PAGES      MAKEINDEX(1L)
  929.  
  930.  
  931.  
  932.             \item \verb=_= (underscore), 95
  933.             \item \verb=~= (grave accent), 96
  934.             \item \{ (left brace), 123
  935.             \item \verb=|= (vertical bar), 124
  936.             \item \} (right brace), 125
  937.             \item \verb=~= (tilde), 126
  938.  
  939.             \indexspace
  940.  
  941.             \item   (space), 32
  942.  
  943.           \end{theindex}
  944.  
  945. FILES
  946.      /usr/local/bin/makeindex
  947.                            executable file
  948.  
  949.      /usr/local/lib/tex/macros/idxmac-amstex.tex
  950.                            TeX macro file used by makeindex
  951.  
  952.      /usr/local/lib/tex/macros/idxmac.tex
  953.                            TeX macro file used by makeindex
  954.  
  955.      /usr/local/lib/tex/macros/makeidx.doc
  956.                            TeX macro file used by makeindex
  957.  
  958.      /usr/local/lib/tex/macros/makeidx.sty
  959.                            TeX macro file used by makeindex
  960.  
  961. SEE ALSO
  962.      ditroff(1L), latex(1L), make.index (1L), qsort(3),  tex(1L),
  963.      troff(1L)
  964.  
  965.      UCSF Enhanced troff/TRANSCRIPT - An Overview, R. P. C. Rodg-
  966.      ers  and  Conrad  Huang,  LSMB  Technical  Report 90-2, UCSF
  967.      School of Pharmacy, San Francisco, 1990.
  968.  
  969.      Index Preparation and Processing, Pehong Chen and Michael A.
  970.      Harrison,  Software: Practice and Experience, 19(9), 897915,
  971.      September 1988.
  972.  
  973.      Automating Index Preparation, Pehong  Chen  and  Michael  A.
  974.      Harrison.   Technical  Report 87/347, Computer Science Divi-
  975.      sion, University of  California,  Berkeley,  1987  (a  LaTeX
  976.      document supplied with makeindex).
  977.  
  978.      MakeIndex: An Index Processor  for  LaTeX,  Leslie  Lamport,
  979.      February 1987 (a LaTeX document supplied with makeindex).
  980.  
  981.      Tools for Printing Indices, Jon L. Bentley and Brian W. Ker-
  982.      nighan,  Electronic Publishing - Origination, Dissemination,
  983.      and  Design,  1(1),  318,  June  1988  (also  available  as:
  984.  
  985.  
  986.  
  987. Sun Release 4.1   Last change: 01 October 1991                 15
  988.  
  989.  
  990.  
  991.  
  992.  
  993.  
  994. MAKEINDEX(1L)     MISC. REFERENCE MANUAL PAGES      MAKEINDEX(1L)
  995.  
  996.  
  997.  
  998.      Computing  Science  Technical  Report  No.  128,  AT&T  Bell
  999.      Laboratories, Murray Hill, NJ 07974, 1986).
  1000.  
  1001. AUTHOR
  1002.      Pehong Chen, Chen &  Harrison  International  Systems,  Inc.
  1003.      Palo Alto, California, USA <chen@renoir.berkeley.edu>.
  1004.      Manual page extensively revised and corrected, and  troff(1)
  1005.      examples created by Rick P. C. Rodgers, UCSF School of Phar-
  1006.      macy <rodgers@cca.ucsf.edu>.
  1007.  
  1008. ACKNOWLEDGMENTS
  1009.      Leslie Lamport  contributed  significantly  to  the  design.
  1010.      Michael Harrison provided valuable comments and suggestions.
  1011.      Nelson Beebe improved on the portable version, and maintains
  1012.      the  source  distribution  for the TeX Users Group.  Andreas
  1013.      Brosig contributed to the German word ordering.  The modifi-
  1014.      cation  to the -ms macros was derived from a method proposed
  1015.      by Ravi Sethi of AT&T Bell Laboratories.  The LOG  and  CON-
  1016.      TRIB files in the makeindex source distribution record other
  1017.      contributions.
  1018.  
  1019.  
  1020.  
  1021.  
  1022.  
  1023.  
  1024.  
  1025.  
  1026.  
  1027.  
  1028.  
  1029.  
  1030.  
  1031.  
  1032.  
  1033.  
  1034.  
  1035.  
  1036.  
  1037.  
  1038.  
  1039.  
  1040.  
  1041.  
  1042.  
  1043.  
  1044.  
  1045.  
  1046.  
  1047.  
  1048.  
  1049.  
  1050.  
  1051.  
  1052.  
  1053. Sun Release 4.1   Last change: 01 October 1991                 16
  1054.  
  1055.  
  1056.  
  1057.